[Bugfix #527] Fix af spawn docs: mark --protocol REQUIRED, add pre-spawn checklist#528
Merged
waleedkadous merged 2 commits intomainfrom Feb 23, 2026
Merged
Conversation
- architect.md: Add pre-spawn checklist, add --protocol to all examples - agent-farm.md: Separate --protocol as REQUIRED, add preconditions and common errors table - SKILL.md (both copies): Mark --protocol REQUIRED in pre-spawn checklist, add "forgetting --protocol" to common mistakes - workflow-reference.md: Fix overview diagram, add spawn error recovery section with recovery flow - Add regression test verifying all af spawn examples include --protocol
…nd skeleton agent-farm.md - codev/roles/architect.md: Same fixes as skeleton copy — pre-spawn checklist, --protocol in all examples, updated quick reference table - codev-skeleton/resources/commands/agent-farm.md: Same fixes as project copy — REQUIRED --protocol, preconditions, common errors - Regression test: Add both missed files to DOC_FILES list (now 7 files)
Contributor
Author
Architect ReviewLow-risk docs-only change. Covers all the right files — architect.md, agent-farm.md, SKILL.md, workflow-reference.md (both codev and skeleton). Every Architect review |
waleedkadous
deleted the
builder/bugfix-527-docs-fix-af-spawn-guidance-to-
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Agents consistently fumble
af spawncommands, wasting 3-4 round-trips. The docs showed--protocolas optional and lacked a pre-spawn checklist in key files.Fixes #527
Root Cause
Three documentation gaps caused the failure pattern:
--protocolappeared optional —architect.mdshowedaf spawn 42without itgit pull, random retries)Fix
Updated 5 documentation files:
codev-skeleton/roles/architect.md: Added pre-spawn checklist section, added--protocolto all examples, updated quick reference tablecodev/resources/commands/agent-farm.md: Separated--protocolas REQUIRED (not just an option), added Preconditions section, added Common Errors table.claude/skills/af/SKILL.md(both copies): Enhanced pre-spawn checklist to include--protocol, added "forgetting --protocol" to common mistakescodev/resources/workflow-reference.md: Fixed overview diagram (af spawn XXXX→af spawn XXXX --protocol spir), added Spawn Failures troubleshooting section with recovery flowTest Plan
bugfix-527-spawn-docs.test.ts) — scans all doc files foraf spawn <number>examples and verifies they include--protocol(or use an exempted form)Diff Stats
6 files changed, 190 insertions(+), 35 deletions(-) — well under 300 LOC threshold